3.1 The built-in table editor
Org makes it easy
to format tables in plain ASCII. Any line with
‘|’ as the
first non-whitespace character is considered part of a table.
‘|’ is also
the column separator. A table might look like this:
| Name | Phone | Age |
|-------+-------+-----|
| Peter | 1234 | 17 |
| Anna | 4321 | 25 |
A table is re-aligned automatically each time you press
<TAB> or <RET> or C-c C-c inside the
table. <TAB> also moves to the next field (<RET> to
the next row) and creates new table rows at the end of the table
or before horizontal lines. The indentation of the table is set
by the first line. Any line starting with
‘|-’ is
considered as a horizontal separator line and will be expanded on
the next re-align to span the whole table width. So, to create
the above table, you would only type
|Name|Phone|Age|
|-
and then press <TAB> to align the table
and start filling in fields. Even faster would be to type
|Name|Phone|Age followed by C-c
<RET>.
When
typing text into a field, Org treats <DEL>,
<Backspace>, and all character keys in a special way, so
that inserting and deleting avoids shifting other fields. Also,
when typing immediately after the cursor was moved into a new
field with <TAB>,
S-<TAB> or <RET>, the
field is automatically made blank. If this behavior is too
unpredictable for you, configure the variables
org-enable-table-editor and
org-table-auto-blank-field.
- Creation and conversion
- C-c |
(
org-table-create-or-convert-from-region)
- Convert the active region to table. If every line contains
at least one TAB character, the function assumes that the
material is tab separated. If every line contains a comma,
comma-separated values (CSV) are assumed. If not, lines are
split at whitespace into fields. You can use a prefix argument
to force a specific separator: C-u forces CSV,
C-u C-u forces TAB, and a numeric argument N
indicates that at least N consecutive spaces, or alternatively
a TAB will be the separator.
If there is no active region, this command creates an empty Org
table. But it's easier just to start typing, like
|Name|Phone|Age <RET> |-
<TAB>.
- Re-aligning and field motion
- C-c C-c
(
org-table-align)
- Re-align the table without moving the cursor.
- <TAB>
(
org-table-next-field)
- Re-align the table, move to the next field. Creates a new
row if necessary.
- S-<TAB>
(
org-table-previous-field)
- Re-align, move to previous field.
- <RET>
(
org-table-next-row)
- Re-align the table and move down to next row. Creates a new
row if necessary. At the beginning or end of a line,
<RET> still does NEWLINE, so it can be used to split a
table.
- M-a
(
org-table-beginning-of-field)
- Move to beginning of the current table field, or on to the
previous field.
- M-e
(
org-table-end-of-field)
- Move to end of the current table field, or on to the next
field.
- Column and row editing
- M-<left>
(
org-table-move-column-left)
- M-<right>
(
org-table-move-column-right)
- Move the current column left/right.
- M-S-<left>
(
org-table-delete-column)
- Kill the current column.
- M-S-<right>
(
org-table-insert-column)
- Insert a new column to the left of the cursor position.
- M-<up>
(
org-table-move-row-up)
- M-<down>
(
org-table-move-row-down)
- Move the current row up/down.
- M-S-<up>
(
org-table-kill-row)
- Kill the current row or horizontal line.
- M-S-<down>
(
org-table-insert-row)
- Insert a new row above the current row. With a prefix
argument, the line is created below the current one.
- C-c -
(
org-table-insert-hline)
- Insert a horizontal line below current row. With a prefix
argument, the line is created above the current line.
- C-c <RET>
(
org-table-hline-and-move)
- Insert a horizontal line below current row, and move the
cursor into the row below that line.
- C-c ^
(
org-table-sort-lines)
- Sort the table lines in the region. The position of point
indicates the column to be used for sorting, and the range of
lines is the range between the nearest horizontal separator
lines, or the entire table. If point is before the first
column, you will be prompted for the sorting column. If there
is an active region, the mark specifies the first line and the
sorting column, while point should be in the last line to be
included into the sorting. The command prompts for the sorting
type (alphabetically, numerically, or by time). When called
with a prefix argument, alphabetic sorting will be
case-sensitive.
- Regions
- C-c C-x M-w
(
org-table-copy-region)
- Copy a rectangular region from a table to a special
clipboard. Point and mark determine edge fields of the
rectangle. If there is no active region, copy just the current
field. The process ignores horizontal separator lines.
- C-c C-x C-w
(
org-table-cut-region)
- Copy a rectangular region from a table to a special
clipboard, and blank all fields in the rectangle. So this is
the “cut” operation.
- C-c C-x C-y
(
org-table-paste-rectangle)
- Paste a rectangular region into a table. The upper left
corner ends up in the current field. All involved fields will
be overwritten. If the rectangle does not fit into the present
table, the table is enlarged as needed. The process ignores
horizontal separator lines.
- M-<RET>
(
org-table-wrap-region)
- Split the current field at the cursor position and move the
rest to the line below. If there is an active region, and both
point and mark are in the same column, the text in the column
is wrapped to minimum width for the given number of lines. A
numeric prefix argument may be used to change the number of
desired lines. If there is no region, but you specify a prefix
argument, the current field is made blank, and the content is
appended to the field above.
- Calculations
- C-c +
(
org-table-sum)
- Sum the numbers in the current column, or in the rectangle
defined by the active region. The result is shown in the echo
area and can be inserted with C-y.
- S-<RET>
(
org-table-copy-down)
- When
current field is empty, copy from first non-empty field above.
When not empty, copy current field down to next row and move
cursor along with it. Depending on the variable
org-table-copy-increment, integer field values
will be incremented during copy. Integers that are too large
will not be incremented. Also, a 0 prefix argument
temporarily disables the increment. This key is also used by
shift-selection and related modes (see Conflicts).
- Miscellaneous
- C-c `
(
org-table-edit-field)
- Edit the current field in a separate window. This is useful
for fields that are not fully visible (see Column
width and alignment). When called with a C-u
prefix, just make the full field visible, so that it can be
edited in place.
- M-x org-table-import
- Import a file as a table. The table should be TAB or
whitespace separated. Use, for example, to import a spreadsheet
table or data from a database, because these programs generally
can write TAB-separated text files. This command works by
inserting the file into the buffer and then converting the
region to a table. Any prefix argument is passed on to the
converter, which uses it to determine the separator.
- C-c |
(
org-table-create-or-convert-from-region)
- Tables can also be imported by pasting tabular text into
the Org buffer, selecting the pasted text with C-x
C-x and then using the C-c | command (see
above under Creation and conversion).
- M-x org-table-export
- Export
the table, by default as a TAB-separated file. Use for data
exchange with, for example, spreadsheet or database programs.
The format used to export the file can be configured in the
variable
org-table-export-default-format. You may
also use properties TABLE_EXPORT_FILE and
TABLE_EXPORT_FORMAT to specify the file name and
the format for table export in a subtree. Org supports quite
general formats for exported tables. The exporter format is the
same as the format used by Orgtbl radio tables, see Translator
functions, for a detailed description.
If you don't like the automatic table editor because it gets
in your way on lines which you would like to start with
‘|’, you can
turn it off with
(setq org-enable-table-editor nil)
Then the only table command that still works
is C-c C-c to do a manual re-align.